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Preface 


Intended Audience 


This manual is intended for VMS system managers, operators, and system 
programmers. 





Document Structure 
This document consists of the following three sections: 
e Description—Provides a full description of the Install Utility (INSTALL). 
e Usage Summary—Outlines the following INSTALL information: 


—Invoking the utility 
—Exiting from the utility 
—Restrictions or privileges required 


e Commands—Describes INSTALL commands, including format, 
parameters, and examples. 





Associated Documents 


For additional information on topics covered in this document, see the 
following manuals: 


e VMS DCL Dictionary 

e Guide to Setting Up a VMS System 

e VMS System Messages and Recovery Procedures Reference Manual 
e = =VMS Linker Utility Manual 

e VMS System Generation Utility Manual 


e = =VMS System Services Reference Manual 
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Conventions 
Convention 


RET 


CTRL/C 


$ SHOW TIME 
O5-JUN-1988 11:55:22 


¢ TYPE MYFILE.DAT 


input-file, ... 


[logical-name] 


quotation marks 
apostrophes 


vill 


Meaning 


In examples, a key name (usually abbreviated) 
shown within a box indicates that you press 

a key on the keyboard; in text, a key name is 
not enclosed in a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key is not usually shown in syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 


A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 
box. 


In examples, system output (what the system 
displays) is shown in black. User input (what 
you enter) is shown in red. 


In examples, a vertical series of periods, or 
ellipsis, means either that not all the data that 
the system would display in response to a 
command is shown or that not all the data a 
user would enter is shown. 


In examples, a horizontal ellipsis indicates 
that additional parameters, values, or other 
information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 


Brackets indicate that the enclosed item is 
optional. (Brackets are not, however, optional 
in the syntax of a directory name in a file 
specification or in the syntax of a substring 
specification in an assignment statement.) 


The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 


New and Changed Features 


The Install Utility (INSTALL) has a new DCL command line interface. To 
invoke the utility, enter the command INSTALL at the DCL prompt. 


Note that Version 4.0 command procedures defining INSTALL as a foreign 
command (INSTALL == $SYS$SYSTEM:INSTALL/COMMAND_MODE) 
will execute successfully with the DCL command interface. 


If you wish to continue using the Version 3.0 INSTALL command syntax, 
which is incompatible with commands described in this manual, enter the 
command: 


$ RUN SYS$SYSTEM: INSTALL 


Alternatively, you can enter the command: 
$¢ MCR INSTAL:. 


Please be aware, however, that DIGITAL does not guarantee that 

Version 3.0 INSTALL command syntax will receive future development. 
DIGITAL recommends that you convert to the command syntax presented in 
this manual. 


INSTALL Description 


The Install Utility (INSTALL) improves the performance of executable 
and shareable images, especially those that run frequently, usually run 
concurrently with several processes, or require special privileges. 


The system defines installed images on internal data structures called known 
file lists. Each entry in the known file list identifies the file name of the 
installed file and the attributes with which it was installed. A separate 
known file list exists for all installed images whose device, directory, and 
file type are identical. For example, all installed images with the file name 
DISK$VOLUME:[MAIN]filename.EXE would be on one known file list, and 
all installed images with the file name DISK$VOLUME;[TEST]filename.EXE 
would be on another known file list. 


Known file lists last only while the system is operating. If the system is 
shut down or fails for any reason, you must reinstall all known images 
after the system is rebooted. For this reason, the site-independent startup 
command procedure, SYS$SYSTEM:STARTUP.COM, includes a series of 
INSTALL commands that install certain system programs as known images. 
You are encouraged to include in the site-specific command procedure, 
SYS$MANAGER:SYSTARTUP.COM, additional INSTALL commands that 
install selected images. 





Reasons to Install Images | 
The Install Utility allows you to do the following: 
e Make programs that require enhanced privileges available for general use. 
e Conserve memory by creating shared images. 


e Improve system performance. 


A nonprivileged process can perform the privileged functions of an executable 
image when it is installed as a privileged image. A user-written system 
service also assumes the privileges it requires when you install it as a 
privileged, shareable image. 


Shared images conserve memory because only one copy of code needs to 

be in memory at any time, and many users can access the code concurrently. 
The Install Utility is the only way to create shared images. Use the /SHARED 
qualifier to install shared images. 


System performance improves when programs are installed because the 
VMS operating system opens any installed file by file ID rather than by 

file name, thus eliminating costly directory operations. Installing images as 
header-resident further enhances performance because the system avoids the 
overhead of a directory operation to read the image header into memory. 
Frequently accessed images, critical to a site’s operations, can be installed as 
open images. This makes the image resident in memory and entirely avoids 
the overhead of opening a file. 
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INSTALL Description 


Because an installed file requires system resources, such as nonpaged dynamic 
memory, install those files that most improve system performance and site- 
requirements. The Install Utility’s LIST command provides information about 
installed images that helps you evaluate the merits of installing images. For 
example, the LIST command calculates the number of times each image is 
accessed, and shows the number of concurrent accesses, so you can determine 
if the installation of the images is justified given the expense of installation. 





Assigning Attributes to Known Images 
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By specifying appropriate qualifiers to INSTALL commands, you can assign 
known images the following attributes: 


e Permanently open—Directory information on the image file remains 
permanently resident, eliminating the usual directory search required 
to locate a file. The cost of keeping an image file permanently open is 
approximately one page of paged dynamic memory per file. 


e Header resident—The header of the image file (native images only) 
remains permanently resident, saving one disk I/O operation per file 
access. For images with single-block file headers, the cost is less than 
one page of paged dynamic memory per file; for images with multiblock 
headers, the cost varies according to the header block count. The images 
must also be declared permanently open. 


e Privileged—Amplified privileges are temporarily assigned to any process 
running the image (executable images only), permitting the process 
to exceed its user authorization file (UAF) privilege restrictions during 
execution of the image. In this way, users with normal privileges can run 
programs that require higher-than-normal privileges. 


e Protected—A shareable image contains protected code, that is, code that 
runs in Kernel or Executive mode but that can be called by a user-level 
image. Protected images must be declared shared. 


e Shared—More than one user can access the read-only and non-copy- 
on-reference read/write sections of the image concurrently, so that only 
one copy of those sections ever need be in physical memory. (Copy-on- 
reference sections always require a separate copy for each process.) The 
image is implicitly declared permanently open. 


¢ Writable—When a shared non-copy-on-reference writable section is 
removed from physical memory (for paging reasons or because no 
processes are referencing it), it is written back to the image file. Any 
updates made by processes mapped to the section, therefore, are 
preserved (while the initial values are lost). The image must also be 
declared shared. 
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Installing Images with the Shared Attribute 


Before installing an image with the shared attribute (using the /SHARE 
qualifier), you must understand the distinction between executable and 
shareable images: 


e An executable image is one linked with the /EXECUTABLE qualifier (or 
without the /SHAREABLE qualifier) of the VMS Linker. For information 
on the VMS Linker, refer to the VMS Linker Utility Manual. 


e A shareable image is one linked with the /SHAREABLE qualifier of the 
VMS Linker; it must subsequently be linked into an executable image to 
be used. (Shareable images are sometimes referred to as linkable images, 
because they can be specified—implicitly or explicitly—as input files 
to the link of another file.) A shareable image is not copied into the 
executable images that link with it. Thus, only one copy of the shareable 
image need be on disk, no matter how many executable images have 
linked with it. 


When you install an image with the shared attribute, permanent system 
global sections are created. Execution of non-copy-on-reference global 
sections requires only one copy per section to be in physical memory, no 
matter how many processes are running the image to which the sections 
belong. 


The number of images you can install with the /SHARED qualifier is 
restricted by the GBLPAGES and GBLSECTIONS system parameters. See 
the description of the System Generation Utility in the VMS System Generation 
Utility Manual. 


When an image is not installed, or is installed without the shared attribute, 
each process running the image requires private sections in memory. (A 
shareable image linked to an executable image need not be installed to be 
executed. At image execution time, the system creates private sections from 
the shareable image. The only exception is that a shareable image containing 
a writable non-copy-on-reference section must be installed as a known image 
with the shared and writable attributes.) 





Installing Images with Privileges 


The VMS operating system allows images to execute in an enhanced privilege 
environment through the following mechanisms: 


e You can install existing executable images with extra privileges to allow a 
nonprivileged process to perform the privileged functions of the image. 


e You can install privileged shareable images. Privileged shareable images 
are used to implement user-written system services, thereby allowing 
nonprivileged images to execute select portions of privileged code without 
enhancing the privileges of each image that uses the privileged portion of 
code. 
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INSTALL Description 


4.1 Privileged Executable Images 


Install executable images with enhanced privileges by using the 
/PRIVILEGED qualifier. Only images linked with the VMS Linker qualifiers 
/NODEBUG and /NOTRACE should be installed with enhanced privilege. 
Installing other images with enhanced privilege can compromise system 
security. 


4.2 Privileged Shareable Images 


The VMS operating system supports user-written system services through a 
mechanism called privileged shareable images. See the VMS System Services 
Reference Manual for a description of how to create privileged shareable 
images. You must link a privileged shareable image with the /PROTECT 
command qualifier or the /OPTIONS positional qualifier of the VMS Linker, 
so that the image acquires its particular form of enhanced privileges. 


e Use the /PROTECT command qualifier when all parts of an image require 
protection. 


e Use the /OPTIONS positional qualifier when only part of a privileged 
shareable image requires protection. 


Then install the privileged shareable image with the Install Utility, specifying 
both the /PROTECTED and /SHAREABLE qualifiers. If you do not follow 
all these steps, you will prevent successful activation of a privileged shareable 
image. 





5 Installing Execute-Only Images 


The image activator allows execution of images to which the caller has 
EXECUTE but not READ access. The support differs slightly for main 
programs and shareable images. 


The /EXECUTE_ONLY qualifier has meaning only for main programs. A 
main program installed with this qualifier is capable of activating shareable 
images to which the process has EXECUTE but not READ access. The image 
activator ignores this qualifier when it is used on images other than main 
programs. 


5.1 Execute-Only Main Programs 
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When a process runs a main program to which it has EXECUTE but not READ 
access, the image activator enters a restricted mode of operation similar to 
that entered when a privileged program is run. That is, all shareable images 
activated during the life of the execute-only program must be installed. In 
addition, the image activator directs VMS Record Management Services 
(RMS) to use only “trusted” logical names when opening image files. Logical 
names associated with EXEC or KERNEL mode are trusted. User-mode and 
supervisor-mode names are not. 


INSTALL Description 


5.2 Execute-Only Shareable Images 


Execute-only shareable images can be executed only in the restricted 
environment established when a main program that references them is run. 
The main program must be installed with the /EXECUTE_ONLY qualifier, 
and all shareable images the program references must be installed. 


When an installed execute-only shareable image is run, the image activator 
enters the same restricted mode of operation that it enters when it detects an 
execute-only main program. That is, only “trusted” logical names are used by 
VMS RMS. 


6 File Specifications for Installed Images 


When using the INSTALL commands, file specifications must name existing 
executable or shareable images. VMS RMS resolves each file specification 
using the following defaults: 


e A device and directory type of SYS$SYSTEM 
e A file type of EXE 


Unless a file shares these defaults, specify a device and directory name as well 
as a file type with each file name. Do not include a version number in the 
file specification. The highest existing version is always used. Specification 
of a version number produces unpredictable results because file lookups for 
known images ignore version numbers. 


All images installed with the /SHARE qualifier must be in directory 
SYS$SHARE, unless you define a logical name for the image. (SYS$SHARE 
is equivalent to SYS$LIBRARY.) 


6.1 Defining Logical Names for Shareable Image Files 


After installing a shareable image, define a logical name for it if it is not 
located in directory SYS$SHARE. For example, if the file specification for 
STATSHR is SYS$SHARE:STATSHR.EXE, no DEFINE command is necessary. 
But if you put STATSHR in SYS$DEVICE:[TEST], you must define STATSHR 
as a logical name before running an executable image that calls it. The logical 
name must be the same one that was used as the input file specification 

for the shareable image when it was linked (this is the same name used in 
installation). For example: 


$ DEFINE STATSHR SYS$SYSDEVICE: [TEST] STATSHR 


With logical names, one shareable image can be substituted for another 
without requiring the calling executable image to relink. You redefine the 
logical name of the shareable image. For example, the following statement 
redefines the file name STATSHR. It becomes the logical name of the 
shareable image SYS$SYSDEVICE:[MAIN]STATSHR.EXE for executable 
images calling STATSHR. 


$ DEFINE STATSHR SYS$SYSDEVICE: [MAIN] STATSHR 


(Logical name redirection in the process or group logical name table is ignored 
when you run a privileged executable image. Only logical names that can be 
redirected by privileged users are allowed.) 
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INSTALL Description 


If the new image is installed with the /SHARED qualifier, executable images 
linked against the old image are mapped to global sections for the new image. 
Otherwise, they are mapped to private sections for the new image. 


The old and new images can have the same name, but they must reside 
in different directories. You should not substitute one version of a file for 
another in the same directory. (Use the REPLACE command to update file 
versions.) 


6.2 Effect of Installing Images on the DCL Command RUN 


The DCL command RUN parses search lists in a manner that favors installed 
images. On its first pass through the search list the RUN command looks up 
images on known file lists and executes each installed image that it finds. On 
its second pass through the search list, the RUN command looks up images 
on disk and executes those images. In essence, then, installing an image alters 
the ordering of a search list. 


7 Installing Shared Images in MA780 Multiport Memory 


To install a shared image so that the global sections reside in a MA780 
multiport memory unit, you enter the DCL command DEFINE to create a 
logical name of the following form: 


GBL$filename shrmem-name:filename 


The following example ensures that any global sections created for an image 
whose file name is STATSHR reside in the MA780 multiport memory unit 
whose logical name is SHRMEM1: 


¢ DEFINE GBL$STATSHR SHRMEM1 : STATSHR 
¢ INSTALL 
INSTALL> ADD /OPEN/SHARED STATSHR 


To create global sections in memory shared by multiple processors requires 
the SHMEM privilege. 





8 Deleting Known Images and Dismounting Volumes 
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System operations are affected by the following characteristics of known 
images: 


e¢ Deletion—A known image is not deleted as soon as the INSTALL 
DELETE command is entered. The deletion occurs only after all processes 
using the image have released it. 


¢ Dismounting—A volume cannot be dismounted while any known file 
lists associated with it contain entries. 


To dismount a volume, you must not only delete all known images associated 
with it. You must wait for all processes using those images to release them 
and for the system to write writable images back to their files. You can use 
the DCL command SHOW DEVICES /FILES to determine the status of the 
files. 


INSTALL Description 


Summary of INSTALL Commands 


Table INS—1 summarizes INSTALL command functions. 


Table INS—1 


Command 


ADD 
CREATE 


DELETE 
EXIT 
HELP 
LIST 


PURGE 


REMOVE 
REPLACE 


INSTALL Command Summary 


Function 


Installs the specified image as a known file entry 


Installs the specified image as a known file entry (identical to 
ADD command) 


Deletes a known file entry 
Exits from INSTALL 
Describes (interactively) how to use INSTALL 


Displays a description of each specified known file entry, global 
sections, and the addresses of known file entry data structures 


Deletes all known file entries installed without the /NOPURGE 
qualifier 


Deletes a known file entry (identical to DELETE command) 


Associates a known file entry with the latest version of the 
image file or modifies the attributes of an installed image 
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INSTALL Usage Summary 


Use the Install Utility (INSTALL) to enhance the performance of selected 
executable and shareable images, to assign enhanced privileges to images, 
and to support user-written system services. The system stores the name 
and attributes of installed images on known file lists. 





FORMAT 


INSTALL [command] 





PARAMETER 


usage summary 
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command 
Specifies an INSTALL command. This parameter is optional. If no command 
is specified, the utility displays its prompt and waits for command input. 


To invoke INSTALL, enter the DCL command INSTALL at the DCL prompt 
as follows: 


¢ INSTALL 
The utility responds with the following prompt: 
INSTALL> 


You can then perform INSTALL operations by entering the appropriate 
INSTALL commands. Alternatively, you can enter a single INSTALL 
command on the same line as the command that invokes the utility, for 
example: 


¢ INSTALL LIST/FULL SYS$SYSTEM: LOGINOUT 


To exit from the Install Utility, enter the EXIT command at the INSTALL> 
prompt or press CTRL/Z. Either method returns control to the DCL command 
level. 


The Install Utility requires that you have the CMKRNL privilege to 
invoke it. It requires the SYSGBL privilege to create system global 
sections and the PRMGBL privilege to create permanent global sections. 


INSTALL 
INSTALL Commands 





INSTALL This section describes the INSTALL commands and provides examples of 


COMMANDS = ‘**r Se. 
ADD 
CREATE 
DELETE 
EXIT 
HELP 
LIST 
PURGE 
REMOVE 
REPLACE 
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INSTALL 
ADD 


ADD 


Installs the specified image file as a known image. 











FORMAT ADD file-spec 

PARAMETER file-spec 
Names the file specification of an image to be installed as a known image. 
The file specification must name an existing executable or shareable image. If 
you omit the device and directory specification, the default SYS$SYSTEM is 
used. The default file type is EXE. A version number must not be specified. 

QUALIFIERS /[NOJACCOUNTING 
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Allows you to enable image-level accounting for selected images when 
image accounting is disabled on the system (with the DCL command SET 
ACC /DISABLE=IMAGE). When image accounting is enabled on the system, 
it logs all images. The /NOACCOUNTING qualifier has no effect. 


/[NOJEXECUTE_ONLY 

The /EXECUTE_ONLY qualifier is only meaningful to main programs. 

It allows the image to activate shareable images to which the user has 
EXECUTE access but has no READ access. All shareable images referenced 
by the program must be installed, and VMS RMS uses “trusted” logical 
names, those created for use in EXEC or KERNEL mode. 


You may not specify this qualifier for an executable image linked with the 
/ TRACEBACK qualifier. 


/[NOJHEADER_RESIDENT 


Installs the file as a known image with a permanently resident header (native 
mode images only). The image is made permanently open even if /OPEN is 
not specified. 


/[NO]LOG 


Lists the newly added known file entry along with any associated global 
sections created by the installation. 


/[NOJOPEN 


Installs the file as a permanently open known image. 


INSTALL 
ADD 


/PRIVILEGED[=(priv-namef[,...])] 


Installs the file as a known image with the privileges specified (executable 
images only). Then, if the image is not located on the system volume, the 
image is made permanently open even if /OPEN is not specified. 


You can specify one or more of the following privilege names: 


ACNT ALLSPOOL ALTPRI 
BUGCHK BYPASS CMEXEC 
CMKRNL DETACH DIAGNOSE 
EXQUOTA GROUP GRPNAM 
GRPPRV LOG_IO MOUNT 
NET MBX OPER PFNMAP 
PHY_IO PRMCEB PRMGBL 
PRMMBX PSWAPM READALL 
SECURITY SETPRV SHARE 
SHMEM SYSGBL SYSLCK 
SYSNAM SYSPRV TMPMBX 
VOLPRO WORLD 


You may not specify this qualifier for an executable image linked with the 
/TRACEBACK qualifier. 


/{NO]JPROTECTED 


Installs the file as a known image that is protected from user-mode and 
supervisor-mode write access. You can only write into the image from 
EXEC or KERNEL mode. The /PROTECTED qualifier together with the 
/SHARE qualifier are used to implement user-written services, which become 
privileged shareable images. 


/[NO]PURGE 

Specifies that the image can be removed by a PURGE operation; if you do 
not specify /PURGE, it can be removed only by a DELETE or REMOVE 
operation. /NOPURGE is the default form of the qualifier. 


/[NOJSHARED 
Installs the file as a shared known image and causes creation of global 


sections for the image. The image is made permanently open even if /OPEN 
is not specified. 


/[NO]WRITABLE 


Installs the file as a writable known image as long as you also specify the 
/SHARED qualifier. The /WRITABLE qualifier is automatically negated if the 
/NOSHARED qualifier is specified. 
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INSTALL 
ADD 





EXAMPLES 
f] ‘INSTALL> ADD /OPEN/SHARED WRKD$: [MAIN] STATSHR 


The command in this example installs the image file STATSHR as a 
permanently open, shared known image. 


2 INSTALL> ADD /OPEN/PRIVILEGED=(GROUP,GRPNAM) GRPCOMM 


The command in this example installs the image file GRPCOMM as a 
permanently open known image with the privileges GROUP and GRPNAM. 


Any process running GRPCOMM receives the GROUP and GRPNAM 
privileges for the duration of the execution of GRPCOMM. The full name 
of GRPCOMM is assumed to be SYS$SYSTEM:GRPCOMM.EXE. 


Kk)  INSTALL> ADD /LOG GRPCOMM 


The command in this example installs the image file GRPCOMM as a known 
image and then displays the newly added known file entry. 
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CREATE 


INSTALL 
CREATE 


Installs the specified image file as a known image. The CREATE command 
is synonymous with the ADD command. 











FORMAT CREATE file-spec 

PARAMETER file-spec 
Names the file specification of an image to be installed as a known image. 
The file specification must name an existing executable or shareable image. If 
you omit the device and directory specification, the default SYS$SYSTEM is 
used. The default file type is EXE. A version number must not be specified. 

QUALIFIERS /[NOJACCOUNTING 


Allows you to enable image-level accounting for selected images when 
image accounting is disabled on the system (with the DCL command SET 
ACC/DISABLE=IMAGE). When image accounting is enabled on the system, 
it logs all images. The /NOACCOUNTING qualifier has no effect. 


/[NOJEXECUTE_ONLY 

The /EXECUTE_ONLY qualifier is meaningful only to main programs. 

It allows the image to activate shareable images to which the user has 
EXECUTE access but has no READ access. All shareable images referenced 
by the program must be installed, and VMS RMS uses “trusted” logical 
names, those created for use in EXEC or KERNEL mode. 


You may not specify this qualifier for an executable image linked with the 
/TRACEBACK qualifier. 


/[NOJHEADER_RESIDENT 

Installs the file as a known image with a permanently resident header (native 
mode images only). The image is made permanently open even if /OPEN is 
not specified. 


/[NOJLOG 


Lists the newly created known file entry along with any associated global 
sections created by the installation. 


/[NOJOPEN 


Installs the file as a permanently open known image. 


/[NO]JPRIVILEGED/=(priv-namef,...])] 


Installs the file as a known image with the privileges specified (executable 
images only). Then, if the image is not located on the system volume, the 
image is made permanently open even if /OPEN is not specified. You 
may not specify this qualifier for an executable image linked with the 

/ TRACEBACK qualifier. 
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/[NOJPROTECTED 


Installs the file as a known image that is protected from user-mode and 
supervisor-mode write access. You can only write into the image from 
EXEC or KERNEL mode. The /PROTECTED qualifier together with the 
/SHARE qualifier are used to implement user-written services, which become 
privileged shareable images. 


/[NO]PURGE 

Specifies that the image can be removed by a PURGE operation; if you do 
not specify /PURGE, it can be removed only by a DELETE or REMOVE 
operation. (/NOPURGE is the default form of the qualifier.) 


/[NO]JSHARED 


Installs the file as a shared known image and causes creation of global 
sections for the image. The image is made permanently open even if /OPEN 
is not specified. 


/[NO]WRITABLE 

Installs the file as a writable known image as long as you also specify the 
/SHARED qualifier. The /WRITABLE qualifier is automatically negated if the 
/NOSHARED qualifier is specified. 





EXAMPLES 


4 INSTALL> CREATE /OPEN/SHARED WRKD$: [MAIN] STATSHR 


The command in this example installs the image file STATSHR as a 
permanently open shared known image. 


2. INSTALL> CREATE /OPEN/PRIVILEGED=(GROUP ,GRPNAM) GRPCOMM 


The command in this example installs the image file GRPCOMM as a 
permanently open known image with the privileges GROUP and GRPNAM. 


Any process running GRPCOMM receives the GROUP and GRPNAM 
privileges for the duration of the execution of GRPCOMM. The full name 
of GRPCOMM is assumed to be SYS$SYSTEM:GRPCOMM.EXE. 


Kk} INSTALL> CREATE /LOG GRPCOMM 
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The command in this example installs the image file GRPCOMM as a known 
image and then displays the newly created known file entry. 


INSTALL 
DELETE 


DELETE 


Deletes a known image. 





FORMAT __ DELETE _ffile-spec 





PARAMETER file-spec 


Names the file specification of an image installed as a known image. 





QUALIFIERS None. 





DESCRIPTION The DELETE command deletes an entry from the known image file list. 
The image’s entry on the known file list and any global sections created 
for the image are deleted. The image itself (that is, the image file) remains 
unaffected. Writable global sections are written back to disk upon their 
removal as known images. 


If a process is accessing global sections when the DELETE command is 
entered, the global sections are deleted only after the operation initiated 

by the process completes. However, once the command is entered, no 
additional processes can access the global sections because they are “marked 
for deletion.” 


The DELETE command is identical to the REMOVE command. 





EXAMPLE 


INSTALL> DELETE WRKD$: [MAIN] STATSHR 


The command in this example deletes the entry for the image STATSHR from 
the known file list. 
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EXIT 
Terminates INSTALL and returns control to the DCL command level. You 
can also exit from INSTALL by pressing CTRL/Z. 

FORMAT EXIT 


PARAMETERS = None. 





QUALIFIERS None. 
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HELP 


Interactively displays information about how to use INSTALL. 





FORMAT HELP [command] 





PARAMETER command 
Specifies the name of a command for which help infomation is to be 
displayed. If you omit a command name, a list of commands is displayed, 
and you are prompted for a command name. 





EXAMPLES 


INSTALL> HELP 


The command in this example displays a list of INSTALL topics and a Topic? 
prompt. Any topic from the list can be entered at the prompt. 


LN) 


INSTALL> HELP LIST 
LIST 
For display of a one-line description of the specified known image, or if 


no file is specified, then for all known images. Use with /FULL to obtain 
a multiline description. 


Format : LIST [file-spec] /qualifier 


QUALIFIER COMBINATION BEHAVIOR 


LIST [file-spec] List the known file entry for file-spec 
LIST List all entries 


Additional information available: 


Qualifiers 
/FULL /GLOBAL /STRUCTURE / SUMMARY 


The command in this example displays information on the LIST command. 
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LIST 


Displays a description of each specified known image or (if no file is 
specified) all known images. 





FORMAT LIST /file-spec] 





PARAMETER file-spec 


Names the file specification of an image installed as a known image. If you 
omit the file specification, INSTALL displays all known file entries. 





QUALIFIERS  §/FULL 


Displays a multiline description of the specified known image, including the 
number of accesses, the number of concurrent accesses, and the number of 
global sections created. The /FULL qualifier with the /GLOBAL qualifier 
shows information on global sections, plus owner and protection codes and 
access control entries, if set. 


/GLOBAL 


Lists global sections for any specified shared image, or if you omit the file 
specification, lists all global sections. 


/STRUCTURE 


Lists addresses of known file entry data structures. 


/SUMMARY 


Used with the /GLOBAL qualifier; displays a summary of global section 
and global page usage on the system, for local and shared memory global 
sections. 





DESCRIPTION You can use the LIST command with the /FULL qualifier to display 

information that is useful in “tuning” the known file database. For example, 
a high entry access count for an image may indicate that system performance 
could benefit if the image were installed /OPEN. Similarly, high entry access 
counts for an image may indicate that installing the image /SHARED—that 
is, with global sections—could improve performance. For a description of 
global sections and global pages, including information on how to estimate 
the size of installed images, see the VMS System Services Reference Manual. 
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EXAMPLES 
f]  INSTALL> List 


The command in this example displays a single-line description of all known 
images. The description includes the file specification of the known image 
and its attributes. 


DISK$VAXVMSRL4: <SYSO.SYSEXE> . EXE 


BLISS32 ;2@ Open@ Shar 

CDU; 4 Open Priv 

COPY ; 4 Open Shar 

DCL; 2 Open Shar Lnkbl 
MOUNTSHR ;6 Open Shar Prot 


SYSMGTMSG; 41 


@ File specification of the known image. 


@® Attribute of known image, as follows: 


Attribute Meaning 

ACNT Image accounting is enabled for the image (/ACCOUNTING) 

CMODE Image is compatibility mode, set by the VAX-11 RSX Linker 

HDR Image header is permanently resident (/HEADER_RESIDENT) 

LNKBL Image is not executable; it is a shareable (linkable) image, set 

| by the VMS Linker 

NOPURG Image cannot be removed by a PURGE operation; it can only 
be removed by a DELETE or REMOVE operation (/NOPURGE) 

OPEN Image is permanently open (/OPEN) 

PROT Image contains protected code (/PROTECTED) 

PRV Image has privileges (/PRIVILEGE=) 

SHAR Image is shared (/SHARED) 

SHM Image has global sections installed in shared memory 
(/SHARED) 

WRT Image is writable (/WRITABLE) 

XONLY Only execute access to image is allowed (/EXECUTE_ONLY) 


(J ~—sINSTALL> LIST/FULL LOGINOUT 


The command in this example displays a multiline description of the known 


image LOGINOUT. 
DISK$VAXVMSRLS : <SYSO .SYSEXE> . EXE 
LOGINOUT ; 3 Open Hdr Shar Priv 
Entry access count = 44 
Current / Maximum shared =3/5@ 
Global section count =20 


Privileges = CMKRNL SYSNAM TMPMBX EXQUOTA SYSPRV @ 
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4 


Ek] INSTALL>LIST /GLOBAL 
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Number of times known file entry has been accessed by this node since it 
became known. 


The first number indicates the current count of concurrent accesses of the 
known file. The second number indicates the highest count of concurrent 
accesses of the file since it was installed. This number appears only if the 
image is installed with the /OPEN qualifier. 


Number of global sections created for the known file; appears only if the 
image is installed with the /SHARED qualifier. 


Translation of the privilege mask; appears only if the image is installed 
with privileges. 


The command in this example displays all global sections for shared images. 


System Global Sections @ 


LBRSHR_004 @ (01000001) © wrt @ PRM © sys @ Pagcnt/Refcnt=1/0O 
CRFSHR_003 (010003E8) WRT PRM SYS Pagcnt/Refcnt=1/1 


27 Global Sections Used, 828/3268 Global Pages Used/Unused © 
Display of global sections in local memory. | 
Name of global section. 


Version number (in hexadecimal) of global section; for shareable 
images only, the high-order byte (01 in CRFSHR_—003) contains major 
identification, and low-order bytes (0003E8 in CRFSHR—003) contain 
minor identification determined by the programmer at link time. For 
executable images, the number is a known unique value determined by 
the system. 


The global section is writable. 


The global section is permanent; TMP indicates a temporary global 
section, which would be created by a program other than the Install 
Utility. 


The global section is systemwide; GRP and a group number indicate a 
groupwide section, which would be created by a program other than 
Install. 


Number of pages in the section and number of page table entries 
currently mapped to this global section. See the VMS System Services 
Reference Manual for a detailed discussion. 


Number of global sections created, number of global pages used, and 
number of global pages unused in local memory. Note that, because of 
arithmetic rounding, the number of global sections created will sometimes 
be greater than the SYSGEN parameter GBLSECTIONS. When the size of 
the system header is being computed, the values of the GBLSECTIONS 
and SYSMWCNT parameters are combined with the size of the fixed 
part of the process header. The result is rounded up to the next page 
boundary. This rounding process sometimes adds space to the global 
section table, depending on the values of the two SYSGEN parameters 


INSTALL 
LIST 


and the amount of system paging that preceded the running of INSTALL 
to create all of the global sections. 


~] INSTALL> LIST/GLOBAL/FULL 


The command in this example displays a complete listing of global sections 
for shared images. The /FULL qualifier adds owner and protection codes to 
the display. 


System Global Sections 
NM_MAILSHR_003 (741A6919) 
NM_MAILSHR_002 (741A6919) 
NM_MAILSHR_001 (741A6919) 

Owner: 
Protection: 


PRM SYS Pagcnt/Refcnt=10/0 
PRM SYS Pagcnt/Refcnt=1/0 
PRM SYS Pagcnt/Refcnt=11/0 


[1,4] @ 
S:RWED,O:RWED,G:RWED,W:RE @ 


@ UIC of the owner of the global section 


E}  INSTALL>LIST /GLOBAL 


The type of access allowed for the image 


When you issue the command in this example, the display shows global 
sections in multiport memory in addition to the global sections for shared 
images. 


System Global Sections @ 


Global Sections in Multiport Memory "SHM" @ 


VMSRTL_001 (010003FC) 


PRM SYS Creator Port=0 © 


Basepfn/Pagcnt=00000000/7 @ 
Port 0 PTE Refcnt=35 © 


659 Global Pages Used, 1329 Global Pages Unused 
15 Global Sections Used, 17 Global Sections Unused © 


1 
2) 


Display of global sections in local memory. 


Display of global sections in shared multiport memory unit named SHM 
by the system manager; one such display appears for each attached 
multiport memory unit. 


Number of the port from which the global section was created. 


Base page frame number (in hexadecimal) and number of pages in the 
section. 


Page table entry (PTE) reference count; one appears for each port where 
the reference count is not 0. 


Number of global pages used, number of global pages unused, number 
of global sections used, and number of global sections unused in shared 
memory. 
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PURGE 


Deletes all known file entries for images installed without the /NOPURGE 
qualifier. 





FORMAT PURGE 





PARAMETERS = None. 





QUALIFIERS None. 





DESCRIPTION The PURGE command deletes all known file entries for images installed 
without the /NOPURGE qualifier. 


If a process is accessing global sections when the PURGE command is 
entered, the global sections are deleted only after the operation initiated 

by the process completes. However, once the command is entered, no 
additional processes can access the global sections because they are “marked 
for deletion.” 





EXAMPLE 
INSTALL> PURGE 


The command in this example deletes all images except those installed with 
the /NOPURGE qualifier. The images themselves (that is, the image files) 
remain unaffected. Writable global sections are written back to disk upon 
their removal as known images. 
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INSTALL 
REMOVE 


REMOVE 


Removes an entry from the known image file list. The REMOVE command 
is synonymous with the DELETE command. 





FORMAT REMOVE file-spec 





PARAMETER _sfile-spec 


Names the file specification of the known image file entry. 





QUALIFIERS — None. 





DESCRIPTION The REMOVE command deletes an entry that appears in the known image 
| ile list. The image’s entry on the known file list and any global sections 
for the image are deleted. The image itself (that is, the image file) remains 
unaffected. Writable global sections are written back to disk upon their 
removal as known images. 


If a process is accessing global sections when the REMOVE command is 
entered, the global sections are deleted only after the operation initiated 

by the process completes. However, once the command is entered, no 
additional processes can access the global sections because they are “marked 
for deletion.” 





EXAMPLE 


INSTALL> REMOVE GRPCOMM 


The command in this example deletes the entry for the known image 
GRPCOMM from the known image file list. 
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REPLACE 


Associates a known image with the latest version of the image file, or 
modifies the attributes of an installed image. 





FORMAT REPLACE file-spec 





PARAMETER file-spec 


Names the file specification of an image installed as a known image. 





QUALIFIERS /[NOJACCOUNTING 
Allows you to enable image-level accounting for selected images when 
image accounting is disabled on the system (with the DCL command SET 
ACC/DISABLE=IMAGE). When image accounting is enabled on the system, 
it logs all images. The /NOACCOUNTING qualifier has no effect. 


/[NOJEXECUTE_ONLY 

The /EXECUTE_ONLY qualifier is meaningful only to main programs. 

It allows the image to activate shareable images to which the user has 
EXECUTE access but has no READ access. All shareable images referenced 
by the program must be installed, and VMS RMS uses “trusted” logical 
names, those created for use in EXEC or KERNEL mode. 


You may not specify this qualifier for an executable image linked with the 
/ TRACEBACK qualifier. 


/[NOJHEADER_RESIDENT 


Installs the file as a known image with a permanently resident header (native 
mode images only). The image is made permanently open even if /OPEN is 
not specified. | 


/[NO]JLOG 


Lists the newly created known file entry along with any associated global 
sections created by the installation. — 


/[NOJOPEN 


Installs the file as a permanently open known image. 


/[NO]JPRIVILEGED[=(priv-namef[,...])] 


Installs the file as a known image with the privileges specified (executable 
images only). Then, if the image is not located on the system volume, the 
image is made permanently open even if /OPEN is not specified. For a 
complete listing of privileges, see the ADD command. 


You may not specify this qualifier for an executable image linked with the 
/ TRACEBACK qualifier. 
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/[NOJPROTECTED 


Installs the file as a known image that is protected from user-mode and 
supervisor-mode write access. You can only write into the image from 
EXEC or KERNEL mode. The /PROTECTED qualifier together with the 
/SHARE qualifier are used to implement user-written services, which become 
privileged shareable images. 


/[NO]JPURGE 

Specifies that the image can be removed by a PURGE operation; if you do 
not specify /PURGE, it can be removed only by a DELETE or REMOVE 
operation. (/NOPURGE is the default form of the qualifier.) 


/[NOJSHARED 


Installs the file as a shared known image and causes creation of global 
sections for the image. The image is made permanently open even if /OPEN 
is not specified. 


/[NO]WRITABLE 

Installs the file as a writable known image as long as you also specify the 
/SHARED qualifier. The /WRITABLE qualifier is automatically negated if the 
/NOSHARED qualifier is specified. 





DESCRIPTION The REPLACE command updates a known file to the latest version found in 
the specified directory. 


You can use the REPLACE command to modify the attributes of currently 
installed images. Either specify new qualifiers, or change the value of 
qualifiers used when installing the image with the ADD (or CREATE) 
command. If you specify no qualifiers, the new image retains the same 
attributes as the old one. If the old image was installed with the /SHARED 
qualifier, the global sections are recreated, probably with new identifiers. 


If a process is accessing global sections when the REPLACE command is 
entered, the global sections are deleted only after the operation initiated 

by the process completes. However, once the command is entered, no 
additional processes can access the global sections because they are “marked 
for deletion.” 





EXAMPLE 
INSTALL> REPLACE GRPCOMM /ACCOUNTING/NOOPEN 


The command in this example replaces the known image GRPCOMM 
with the latest version of the image, while enabling image accounting and 
removing the OPEN attribute for this version. 


The full name of the file specification is assumed to be 
SYS$SYSTEM:GRPCOMM.EXE. 
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